Inside Macintosh: Imaging with QuickDraw
Previous | Chapter Top | Chapter Contents | Next |
Use the OpenCPicture function to begin defining a picture; OpenCPicture collects your subsequent drawing commands--which are described in the other chapters of this book--in a Picture record. You can use the PicComment procedure to include picture comments in your picture definition. To complete the collection of drawing and picture comment commands that define your picture, use the ClosePicture procedure. When you are finished using a picture not stored in a 'PICT' resource, use the KillPicture procedure to release its memory. (To release the memory for a picture stored in a 'PICT' resource, use the Resource Manager procedure ReleaseResource .)
The OpenCPicture function works on all Macintosh computers running System 7. Pictures created with the OpenCPicture function can be drawn on all versions of Macintosh system software. The OpenPicture function, which was created for earlier versions of system software, is described here for completeness.
To begin defining a picture in extended version 2 format, use the OpenCPicture function.
FUNCTION OpenCPicture (newHeader: OpenCPicParams): PicHandle;
TYPE OpenCPicParams =
RECORD
srcRect: Rect; {optimal bounding rectangle }
{ for displaying picture at }
{ resolution indicated in }
{ hRes, vRes fields}
hRes: Fixed; {best horizontal resolution; }
{ $00480000 specifies 72 dpi}
vRes: Fixed; {best vertical resolution; }
{ $00480000 specifies 72 dpi}
version: Integer; {set to -2}
reserved1: Integer; {reserved; set to 0}
reserved2: LongInt; {reserved; set to 0}
END;
The OpenCPicture function returns a handle to a new Picture record (described on Picture ). Use the OpenCPicture function to begin defining a picture; OpenCPicture collects your subsequent drawing commands in this record. When defining a picture, you can use all other QuickDraw drawing routines described in this book, with the exception of CopyMask , CopyDeepMask , SeedFill , SeedCFill , CalcMask , and CalcCMask . (Nor can you use the PlotCIcon procedure, described in Inside Macintosh: More Macintosh Toolbox .)
You can also use the PicComment procedure (described on PicComment ) to include picture comments in your picture definition.
The OpenCPicture function creates pictures in the extended version 2 format. This format permits your application to specify resolutions when creating images.
Use the OpenCPicParams record you pass in the newHeader parameter to specify the horizontal and vertical resolution for the picture, and specify an optimal bounding rectangle for displaying the picture at this resolution. When you later call the DrawPicture procedure (described on DrawPicture ) to play back the saved picture, you supply a destination rectangle, and DrawPicture scales the picture so that it is completely aligned with the destination rectangle. To display a picture at a resolution other than that at which it was created, your application should compute an appropriate destination rectangle by scaling its width and height by the following factor:
scale factor = destination resolution / source resolution
For example, if a picture was created at 300 dpi and you want to display it at 75 dpi, then your application should compute the destination rectangle width and height as 1/4 of those of the picture's bounding rectangle.
The OpenCPicture function calls the HidePen procedure, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen procedure just after OpenCPicture , or you called ShowPen previously without balancing it by a call to HidePen ).
Use the handle returned by OpenCPicture when referring to the picture in subsequent routines, such as the DrawPicture procedure.
After defining the picture, close it by using the ClosePicture procedure, described on ClosePicture . To draw the picture, use the DrawPicture procedure, described on DrawPicture .
After creating the picture, your application can use the GetPictInfo function (described on GetPictInfo ) to gather information about it. The PictInfo record (described on PictInfo ) returned by GetPictInfo returns the picture's resolution and optimal bounding rectangle.
When creating a picture, you should generally use the ClosePicture procedure to finish it before you open the Printing Manager with the PrOpen procedure. There are two main reasons for this. First, you should allow the printing driver to use as much memory as possible. Second, the Printing Manager creates its own type of graphics port--one that replaces the standard QuickDraw drawing operations stored in the grafProcs field of a CGrafPort or GrafPort record; to avoid unexpected results when creating a picture, you should draw into a graphics port created with QuickDraw instead of drawing into a printing port created by the Printing Manager.
After calling OpenCPicture , be sure to finish your picture definition by calling ClosePicture before you call OpenCPicture again. You cannot nest calls to OpenCPicture .
Always use the ClipRect procedure to specify a clipping region appropriate for your picture before you call OpenCPicture . If you do not use ClipRect to specify a clipping region, OpenCPicture uses the clipping region specified in the current graphics port. If the clipping region is very large (as it is when a graphics port is initialized) and you scale the picture when drawing it, the clipping region can become invalid when DrawPicture scales the clipping region--in which case, your picture will not be drawn. On the other hand, if the graphics port specifies a small clipping region, part of your drawing may be clipped when you draw it. Setting a clipping region equal to the port rectangle of the current graphics port, as shown in Listing 7-1 , always sets a valid clipping region.
The PrOpen procedure is described in the chapter "Printing Manager" in this book. The ClipRect procedure is described in the chapter "Basic QuickDraw" in this book. The ShowPen and HidePen procedures are described in the chapter "QuickDraw Drawing" in this book.
Listing 7-1 illustrates the use of the OpenCPicture function.
The OpenPicture function, which was created for earlier versions of system software, is described here for completeness. To create a picture, you should use the OpenCPicture function, which allows you to specify resolutions for your pictures, as explained in the previous routine description.
FUNCTION OpenPicture (picFrame:Rect): PicHandle;
The OpenPicture function returns a handle to a new Picture record (described on Picture ). You can use the OpenPicture function to begin defining a picture; OpenPicture collects your subsequent drawing commands in this record. When defining a picture, you can use all other QuickDraw drawing routines described in this book, with the exception of CopyMask , CopyDeepMask , SeedFill , SeedCFill , CalcMask , and CalcCMask . (Nor can you use the PlotCIcon procedure, described in Inside Macintosh: More Macintosh Toolbox .) You can also use the PicComment procedure (described on PicComment ) to include picture comments in your picture definition.
The OpenPicture function creates pictures in the version 2 format on computers with Color QuickDraw when the current graphics port is a color graphics port. Pictures created in this format support color drawing operations at 72 dpi. On computers supporting only basic QuickDraw, or when the current graphics port is a basic graphics port, this function creates pictures in version 1 format. Pictures created in version 1 format support only black-and-white drawing operations at 72 dpi.
Use the handle returned by OpenPicture when referring to the picture in subsequent routines, such as the DrawPicture procedure.
The OpenPicture function calls the HidePen procedure, so no drawing occurs on the screen while the picture is open (unless you call the ShowPen procedure just after OpenPicture or you called ShowPen previously without balancing it by a call to HidePen ).
After defining the picture, close it by using the ClosePicture procedure, described on ClosePicture . To draw the picture, use the DrawPicture procedure, described on DrawPicture .
The version 2 and version 1 picture formats support only 72-dpi resolution. The OpenCPicture function creates pictures in the extended version 2 format. The extended version 2 format, which is created by the OpenCPicture function on all Macintosh computers running System 7, permits your application to specify additional resolutions when creating images.
See the description of the OpenCPicture function for its list of special considerations, all of which apply to OpenPicture .
Version 1 pictures are limited to 32 KB. You can determine the picture size while it's being formed by calling the Memory Manager function GetHandleSize .
To insert a picture comment into a picture that you are defining or into your printing code, use the PicComment procedure.
PROCEDURE PicComment (kind,dataSize:Integer;
dataHandle:Handle);
When used after your application begins creating a picture with the OpenCPicture (or OpenPicture ) function, the PicComment procedure inserts the specified comment into the Picture record. When sent to a printer driver after your application uses the PrOpenPage procedure, PicComment passes the data or commands in the specified comment directly to the printer.
Picture comments contain data or commands for special processing by output devices, such as printers. For example, using the SetLineWidth comment, your application can draw hairlines--which are not available with standard QuickDraw calls--on any PostScript LaserWriter printer and on the QuickDraw LaserWriter SC printer.
Usually printer drivers process picture comments, but applications can also do so. For your application to process picture comments, it must replace the StdComment procedure pointed to by the commentProc field of the CQDProcs or QDProcs record, which in turn is pointed to by the grafProcs field of a CGrafPort or GrafPort record. The default StdComment procedure provided by QuickDraw does no comment processing whatsoever. You can use the SetStdCProcs procedure to assist you in changing the CQDProcs record, and you can use the SetStdProcs procedure to assist you in changing the QDProcs record.
If you create and process your own picture comments, you should define comments so that they contain information that identifies your application (to avoid using the same comments as those used by Apple or by other third-party products). You should define a comment as an ApplicationComment comment type with a kind value of 100. The first 4 bytes of the data for the comment should specify your application's signature. (See the chapter "Finder Interface" in Inside Macintosh: Macintosh Toolbox Essentials for information about application signatures.) You can use the next 2 bytes to identify the type of comment--that is, to specify a kind value to your own application.
Suppose your application signature were 'WAVE' , and you wanted to use the value 128 to identify a kind value to your own application. You would supply values to the kind and data parameters to PicComment as follows:
kind = 100; data = 'WAVE' [4 bytes] + 128 [2 bytes] + additional data [ n bytes]
Your application can then parse the first 6 bytes of the comment to determine whether and how to process the rest of the data in the comment. It is up to you to publish information about your comments if you wish them to be understood and used by other applications.
These former picture comments are now obsolete: SetGrayLevel , ResourcePS , PostScriptFile , and TextIsPostScript .
See Appendix B, "Using Picture Comments for Printing," in this book for information about using picture comments to print with features that are unavailable with QuickDraw. See the chapter "QuickDraw Drawing" in this book for information about the QDProcs record and the StdComment and SetStdProcs procedures. See the chapter "Color QuickDraw" in this book for information about the CQDProcs record and the SetStdCProcs procedure.
To complete the collection of drawing commands and picture comments that define your picture, use the ClosePicture procedure.
PROCEDURE ClosePicture;
The ClosePicture procedure stops collecting drawing commands and picture comments for the currently open picture. You should perform one and only one call to ClosePicture for every call to the OpenCPicture (or OpenPicture ) function.
The ClosePicture procedure calls the ShowPen procedure, balancing the call made by OpenCPicture (or OpenPicture ) to the HidePen procedure.
The ShowPen and HidePen procedures are described in the chapter "QuickDraw Drawing" in this book.
Listing 7-1 illustrates the use of the ClosePicture procedure.
To release the memory occupied by a picture not stored in a 'PICT' resource, use the KillPicture procedure.
PROCEDURE KillPicture (myPicture:PicHandle);
The KillPicture procedure releases the memory occupied by the picture whose handle you pass in the myPicture parameter. Use this only when you're completely finished with a picture.
If you use the Window Manager procedure SetWindowPic to store a picture handle in the window record, you can use the Window Manager procedure DisposeWindow or CloseWindow to release the memory allocated to the picture; these procedures automatically call KillPicture for the picture.
If the picture is stored in a 'PICT' resource, you must use the Resource Manager procedure ReleaseResource instead of KillPicture . The Window Manager procedures DisposeWindow and CloseWindow will not delete it; instead, you must call ReleaseResource before calling DisposeWindow or CloseWindow .